<html xmlns="http://www.w3.org/1999/xhtml" id="request-types">
  <head>
    <title>LPS Request Types</title>
    <meta http-equiv="Content-Type" 
          content="text/html; charset=iso-8859-1"/>
  </head>
  
  <body>
    <h1>LPS Request Types</h1>
    <p> 
      This document briefly describes LPS request types.  It assumes
      that you are generally familiar with <a target="_blank"
      href="http://www.w3.org/Protocols/rfc2068/rfc2068">HTTP</a>, <a
      target="_blank" href="http://www.w3.org/Addressing/">URLs</a>,
      and the LPS architecture described in <xref
      linkend="architecture"/>.  For related
      details on LPS configurations and settings, see <xref
      linkend="deployers-guide"/>.
    </p>
    
    <h2><a name="request-types"/>What are LPS Request Types?</h2>
    
    <p>
      In general, an URL that is used to request a Laszlo application
      is of the form:
    </p>
    
    <code>http://myhost[:myport]/mywebapp/myapp.lzx?lzt=<var>type</var></code>
    
    <p>
      Everything before the <code>?</code> character can typically
      be configured via settings in your Servlet Container and/or
      Web Server.  The value of the <code>lzt</code> query parameter
      is interpreted by the LPS as a <dfn>request type</dfn>.
      Here are the standard request types:
    </p>
    
    <h3>HTML Request Types</h3>
    
    <p>These request types return an HTML page that displays the
    application.  The mime-type of the response is
    <code>text/html</code>.</p>
    
    <dl>
      <dt><code>lzt=html</code></dt>
      <dd>
      This request causes the LPS to respond with an HTML wrapper page
      for the Laszlo application.  The HTML page presents the
      application.  The title and background color of the application
      are set to the title and background color of the application
      (the values of its <code>canvas</code> <code>title</code> and
      <code>bgcolor</code> attributes, if present).
      
      <p>The page that this SWF returns uses JavaScript to include the
      Laszlo application.</p>
      </dd>
      
      <dt><code>lzt=html-object</code></dt><dd>
      
      Same as <code>lzt=html</code>, except this page embeds the
      <code>&lt;object&gt;</code> and <code>&lt;embed&gt;</code> tags
      directly in the HTML page.  This is the traditional technique
      for including applications that is used on most web sites, but
      it is incompatible with the announced changes to Internet
      Explorer.
      </dd>

      <dt><code>lzt=window</code></dt><dd>
      
      Show the application in a popup window sized to the canvas.
      </dd>
    </dl>

    <h3>Embedding Request Types</h3>
    <p>These request types are used to embed an application in an HTML
    page.  Different requests are available depending on the request
    is included on the server (<code>object-tag</code>) or the client
    (everything else); whether the embedding technique is compatible
    with the announced changes to Internet Explorer
    (<code>embed</code> and <code>js</code>) or uses traditional
    embedding techniques (<code>object-tag</code>), and whether it
    creates <code>&lt;object&gt;</code> and <code>&lt;embed&gt;</code>
    tags (<code>embed</code>, <code>js</code>, and
    <code>object-tag</code>) or simply returns the swf file that
    contains the application (<code>swf</code>).</p>

    <dl>
      <dt><code>lzt=embed</code></dt><dd>
      
      Returns a JavaScript include file that is suitable for the
      target of an HTML <code>&lt;script&gt;</code> tag.  The file
      embeds the application into the HTML page at the site of the
      <code>&lt;script&gt;</code> tag.  This is appropriate for
      including an application in a way that is compatible with the
      announced changes to Internet Explorer.
      
      <p>Usage:</p><pre>
&lt;script type="text/javascript" language="JavaScript"
        src="http://localhost:8080/lps-@VERSIONID@/examples/hello.lzx?lzt=embed"&gt;
&lt;/script&gt;</pre>
      </dd>

      <dt><code>lzt=js</code></dt><dd>
      
      Same as <code>lzt=embed</code>, except the included file
      depends on the functions defined in the <a
      href="../../lps/includes/embed.js"><code>embed.js</code></a> file.
      
      <p>Usage:</p><pre>
&lt;html&gt;
&lt;head&gt;
&#x2026;
&lt;script type="text/javascript" language="JavaScript"
        src="http://localhost:8080/lps-@VERSIONID@/lps/includes/embed.js"/ &gt;
&lt;/head&gt;
&lt;body&gt;
&#x2026;
&lt;script type="text/javascript" language="JavaScript"
        src="http://localhost:8080/lps-@VERSIONID@/examples/hello.lzx?lzt=js"&gt;
&lt;/script&gt;
&#x2026;
&lt;/body&gt;
&lt;/html&gt;
</pre>
      </dd>

      <dt><code>lzt=object-tag</code></dt><dd>
      
      Returns the HTML <code>&lt;object&gt;</code> and
      <code>&lt;embed&gt;</code> tags that embed the application into
      an HTML page.  This is useful for server-side includes, when
      compatability with the announced changes to Internet Explorer is
      not necessary.
      </dd>

      <dt><code>lzt=swf</code></dt><dd>
      
      Returns the SWF file that represents the application, without
      any HTML. This is used to embed a Laszlo application in an HTML
      page.  (Most of the other request types generate code that
      includes a URL with this request type.)  The mime-type returned
      by this request is <code>application/x-shockwave-flash</code>.
      </dd>
    </dl>

    <h3>Debugging Request Types</h3>
    <dl>
      <dt><code>lzt=app_console</code></dt>
      <dd>
      <p>This request causes the LPS to respond with an HTML wrapper
      page for the Laszlo application.  The HTML page presents the
      application.  It also displays compilation warnings for the
      application, and links to development environment commands and
      developer resources.  These commands are described <a
      href="../help/app-viewer.html">here</a>.</p>
      
      <p>This is the default request.  If no <code>lzt</code> query
      string variable is present, the value is assumed to be
      <code>html</code>.</p>
      
      <p>The mime-type returned by this request is
      <code>text/html</code>.</p>
      </dd>
      
      <dt><code>lzt=source</code></dt>
      <dd>
        <p>Show the source in a &lt;textarea&gt; HTML element.  The
        mime-type returned by this request is <code>text/html</code>.</p>
      </dd>
      
      <dt><code>lzt=xml</code></dt>
      <dd>
      <p>Show the source as plain XML (for XML-aware browsers).  The
      mime-type returned by this request is <code>text/xml</code>.</p>
      </dd>
    </dl>
    
    <h3>Implementation Request Types</h3>
    <p>These request types are used in the implementation and testing
    of the LPS.  Their behavior and existence should not be relied on,
    and they may change in future releases.
    </p>
    
    <ul>
      <li><code>lzt=canvas-xml</code></li>
      <li><code>lzt=deployment</code></li>
      <li><code>lzt=inline-examples</code></li>
      <li><code>lzt=krank</code></li>
      <li><code>lzt=krank-abort</code></li>
      <li><code>lzt=v1</code></li>
    </ul>
    
    <h2><a name="query-parameters"/>Other Query Parameters</h2>
    
    <p>
      The <code>debug=true</code> query parameter can be used to include
      the debugger in an application.  
    </p>
    <p id="debuglog-parameter">
      The <code>debuglog=true</code> query parameter can be used to
      log debug messages to the server log.  See <xref
      linkend="logging-to-the-server"/> for information about the use
      of this parameter.
    </p>
    <p class="bodytext">
      The <code>?lzrecompile=true</code> query parameter can be used to force the
      LPS to recompile an application (.lzx only, not .lzo) even when the compilation manager's
      dependency option is set to <i>never</i>.  (See <xref linkend="deployers-guide"/> 
      for details on the compilation manager's dependency option).  If the administrator
      password is set, you must also provide the password in <code>pwd=</code> query parameter
      for the recompile to take effect.
    </p>
    <p class="bodytext">
      The <code>?pwd=passwd</code> query string can be used to pass
      in the LPS administrative password.
    </p>
    <p>
      A running Laszlo application can get access to any of the
      query strings that was given in the URL used to access it
      via the LFC's LzBrowser service's getInitArg method.  For
      example if the following URL:
    </p>
    <code>
      http://host:port/myapps/wooker.lzx?wookie=Chewie
    </code>
    <p>
      were used to access the following app:
    </p>
    <code>
      &lt;canvas debug="true"&gt;
        &lt;script&gt;
          var wookieName = LzBrowser.getInitArg('wookie');
          Debug.write("The Wookie's Name: " + wookieName);
        &lt;/script&gt;
      &lt;/canvas&gt;
    </code>
    <p>
      the debugger would display
    </p>
    <code>
      The Wookie's Name: Chewie
    </code>
    <p>
      Note that query strings that conflict with the LFC global namespace
      will be lost (i.e. canvas or bgcolor).
    </p>
    <h2>Administrative Requests</h2>
    <p>
      A password may be required for Administrative Requests.  See
      <xref linkend="deployers-guide"/> for
      more details.
    </p>
    <dl>
      <dt><code>lzt=log</code></dt><dd>
      Show the current log file as <code>text/html</code>.
      </dd>
      
      <dt><code>lzt=clearlog</code></dt><dd>
      Clears the current log file.
      </dd>
      
      <dt><code>lzt=logconfig</code></dt><dd>
      Show LPS log4j configuration as <code>text/xml</code>.
      </dd>
      
      <dt><code>lzt=clearcache</code></dt><dd>
      Clear LPS media, data, and compilation caches.
      Return a <code>text/html</code> status message.
      </dd>
      
      <dt><code>lzt=serverinfo</code></dt><dd>
      Show LPS configuration information as <code>text/xml</code>.
      </dd>
      
      <dt><code>lzt=cacheinfo</code></dt><dd>
      Show LPS media and data cache information as <code>text/xml</code>.
      </dd>
      
      <dt><code>lzt=errorcount</code></dt><dd>
      Show the number of LPS errors as <code>text/xml</code>.
      </dd>
      
      <dt><code>lzt=errorcount&amp;clear=1</code></dt><dd>
      Clear LPS error count. 
      </dd>
      
      <dt><code>lzt=stat</code></dt><dd>
      Monitor server statistics.
      </dd>
      
      <dt><code>lzt=gc</code></dt><dd>
      Run the garbage collector.
      </dd>
    </dl>    
    
    <h2>Preprocessed Requests</h2>
    <p>
      The LPS also supports using dynamic, server-side back-end
      processors (e.g., PHP, JSP) to generate LZX application source
      code before the LPS compiles and serves it.  For URLs that end
      in <code>.lzx</code> for which the LPS can not find a matching
      source file on disk, the LPS removes the
      <code>.lzx</code> suffix and uses HTTP GET to retrieve the content of
      the modified URL.  The returned content
      should be a valid LZX file.  The LPS
      compiles and serves an application based on the dynamically
      generated source code.  For example see the
      <code>hello.jsp</code> file in the examples directory.  This
      example generates a Laszlo application that contains
      information about the current time and session.  You can see
      the generated LZX source at:
    </p>
    <pre>http://localhost:8080/lps-@VERSIONID@/examples/hello.jsp.lzx?lzt=source</pre>
    <p>
      and the generated application at:
    </p>
    <pre>http://localhost:8080/lps-@VERSIONID@/examples/hello.jsp.lzx</pre>
    
    <caution>The use of dynamically generated LZX circumvents the LPS
    compilation cache, and compiles an application for each request.
    This is not recommended for use in deployment.  Dynamic behavior
    is best handled by a static application, that requests data and
    resources from the server during its initialization.  See <xref
    linkend="media-resources.runtime-resources"/> of <xref
    linkend="media-resources"/> for more information.</caution>
    
  </body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
